---
title: "Checkbox Group"
description: "A CheckboxGroup allows users to select one or more items from a list of choices."
---

import {checkboxGroupContent} from "@/content/components/checkbox-group";

# Checkbox Group

A CheckboxGroup allows users to select one or more items from a list of choices.

<ComponentLinks component="checkbox" storybook="checkboxgroup" reactAriaHook="useCheckboxGroup" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add checkbox",
    npm: "npm install @heroui/checkbox",
    yarn: "yarn add @heroui/checkbox",
    pnpm: "pnpm add @heroui/checkbox",
    bun: "bun add @heroui/checkbox"
  }}
/>


## Import

HeroUI exports 2 checkbox-related components:

- **CheckboxGroup**: The root component, it wraps the label and the wrapper.
- **Checkbox**: The checkbox component.

<ImportTabs
  commands={{
    main: 'import {CheckboxGroup, Checkbox} from "@heroui/react";',
    individual: 'import {CheckboxGroup, Checkbox} from "@heroui/checkbox";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={checkboxGroupContent.usage} />

### Disabled

<CodeDemo title="Disabled" files={checkboxGroupContent.disabled} />

### Horizontal

<CodeDemo title="Horizontal" files={checkboxGroupContent.horizontal} />

### Controlled

You can use the `value` and `onValueChange` properties to control the checkbox input value.

<CodeDemo title="Controlled" files={checkboxGroupContent.controlled} />

### Invalid

<CodeDemo title="Invalid" files={checkboxGroupContent.invalid} />

## Slots

- **base**: Checkbox group root wrapper, it wraps the label and the wrapper.
- **wrapper**: Checkbox group wrapper, it wraps all checkboxes.
- **label**: Checkbox group label, it is placed before the wrapper.
- **description**: The description of the checkbox group.
- **errorMessage**: The error message of the checkbox group.

### Custom Styles

You can customize the `CheckboxGroup` component by passing custom Tailwind CSS classes to the component slots.

<CodeDemo title="Custom Styles" files={checkboxGroupContent.customStyles} />

### Custom Implementation

In case you need to customize the checkbox even further, you can use the `useCheckboxGroup` hook to create your own implementation.

<CodeDemo title="Custom Implementation" files={checkboxGroupContent.customImplementation} />

> **Note**: We used [Tailwind Variants](https://www.tailwind-variants.org/) to implement the styles above, you can use any other library such as [clsx](https://www.npmjs.com/package/clsx) to achieve the same result.

<Spacer y={4} />

## API

### Checkbox Group Props

<APITable
  data={[
    {
      attribute: "children",
      type: "ReactNode[] | ReactNode[]",
      description: "The checkboxes items.",
      default: "-"
    },
    {
      attribute: "orientation",
      type: "vertical | horizontal",
      description: "The axis the checkbox group items should align with.",
      default: "vertical"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The color of the checkboxes.",
      default: "primary"
    },
    {
      attribute: "size",
      type: "xs | sm | md | lg | xl",
      description: "The size of the checkboxes.",
      default: "md"
    },
    {
      attribute: "radius",
      type: "none | base | xs | sm | md | lg | xl | full",
      description: "The radius of the checkboxes.",
      default: "md"
    },
    {
      attribute: "name",
      type: "string",
      description: "The name of the CheckboxGroup, used when submitting an HTML form.",
      default: "-"
    },
    {
      attribute: "label",
      type: "string",
      description: "The label of the CheckboxGroup.",
      default: "-"
    },
    {
      attribute: "value",
      type: "string[]",
      description: "The current selected values. (controlled)",
      default: "-"
    },
    {
      attribute: "lineThrough",
      type: "boolean",
      description: "Whether the checkboxes label should be crossed out.",
      default: "false"
    },
    {
      attribute: "defaultValue",
      type: "string[]",
      description: "The default selected values. (uncontrolled)",
      default: "-"
    },
    {
      attribute: "isInvalid",
      type: "boolean",
      description: "Whether the checkbox group is invalid.",
      default: "false"
    },
    {
      attribute: "validationState",
      type: "valid | invalid",
      description: "Whether the inputs should display its \"valid\" or \"invalid\" visual styling. (Deprecated) use isInvalid instead.",
      default: "-"
    },
    {
      attribute: "description",
      type: "ReactNode",
      description: "The checkbox group description.",
      default: "-"
    },
    {
      attribute: "errorMessage",
      type: "ReactNode | ((v: ValidationResult) => ReactNode)",
      description: "The checkbox group error message.",
      default: "-"
    },
    {
      attribute: "validate",
      type: "(value: string[]) => ValidationError | true | null | undefined",
      description: "Validate input values when committing (e.g. on blur), returning error messages for invalid values. Validation errors are displayed upon form submission if validationBehavior is set to native. For real-time validation, use the isInvalid prop.",
      default: "-"
    },
    {
      attribute: "validationBehavior",
      type: "native | aria",
      description: "Whether to use native HTML form validation or ARIA validation. When wrapped in a Form component, the default is `aria`. Otherwise, the default is `native`.",
      default: "native"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the checkbox group is disabled.",
      default: "false"
    },
    {
      attribute: "isRequired",
      type: "boolean",
      description: "Whether user checkboxes are required on the input before form submission.",
      default: "false"
    },
    {
      attribute: "isReadOnly",
      type: "boolean",
      description: "Whether the checkboxes can be selected but not changed by the user.",
      default: "-"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the animation should be disabled.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\" | \"wrapper\" | \"label\", string>>",
      description: "Allows to set custom class names for the checkbox group slots.",
      default: "-"
    }
  ]}
/>

### Checkbox Group Events

<APITable
  data={[
    {
      attribute: "onChange",
      type: "(value: string[]) => void",
      description: "Handler that is called when the value changes.",
      default: "-"
    },
    {
      attribute: "onValueChange",
      type: "(value: T) => void",
      description: "Handler that is called when the element's selection state changes.",
      default: "-"
    }
  ]}
/>
